{smcl}
{* 28dec2018}{...}
{hi:help symbolpalette}{...}
{right:{browse "http://repec.sowi.unibe.ch/stata/palettes/"}}
{right:{browse "http://github.com/benjann/palettes/"}}
{hline}

{title:Title}

{pstd}{hi:symbolpalette} {hline 2} Symbol palettes


{marker syntax}{...}
{title:Syntax}

{pstd}
    Syntax 1: Retrieve (and display) a palette

{p 8 15 2}
    {cmd:symbolpalette} [{help symbolpalette##palette:{it:palette}}]
        [{cmd:,} {help symbolpalette##opts:{it:palette_options}}
        {help symbolpalette##gopts:{it:graph_options}} ]

{pstd}
    Syntax 2: Display multiple palettes

{p 8 15 2}
    {cmd:symbolpalette} [{cmd:,} {help symbolpalette##opts:{it:palette_options}}
        {help symbolpalette##gopts:{it:graph_options}} ] {cmd::} [ {it:list_of_palettes} ]

{pstd}
    where {it:list_of_palettes} is

{p 8 15 2}
    {help symbolpalette##palette:{it:palette}} [{cmd:,} {help symbolpalette##opts:{it:palette_options}}]
    [ {cmd:/} {help symbolpalette##palette:{it:palette}} [{cmd:,} {help symbolpalette##opts:{it:palette_options}}] {cmd:/} ... ]


{synoptset 20 tabbed}{...}
{marker palette}{synopthdr:palette}
{synoptline}
{syntab:Main ({stata "symbolpalette: default / lean / tufte / pplain / pblind":{it:view}})}
{synopt:{helpb symbolpalette##default:default}}15 symbols as in Stata's monochrome schemes; the default{p_end}
{synopt:{helpb symbolpalette##lean:lean}}15 symbols as in {cmd:lean} by Juul (2003){p_end}
{synopt:{helpb symbolpalette##tufte:tufte}}15 symbols as in {cmd:tufte} by Atz (2011){p_end}
{synopt:{helpb symbolpalette##pplain:pplain}}15 symbols as in {cmd:plotplain} by Bischof (2017){p_end}
{synopt:{helpb symbolpalette##pblind:pblind}}14 symbols as in {cmd:plotplainblind} by Bischof (2017){p_end}

{syntab:Custom}
{synopt:{it:{help symbolpalette##symbollist:symbollist}}}custom list of symbols{p_end}
{synopt:{it:{help symbolpalette##myname:myname}}}custom palette provided by program {cmd:symbolpalette_}{it:myname}{p_end}
{synoptline}


{synoptset 20}{...}
{marker opts}{synopthdr:palette_options}
{synoptline}
{synopt:{helpb symbolpalette##n:n({it:#})}}specify size of palette (number of symbols)
    {p_end}
{synopt:{helpb symbolpalette##select:{ul:s}elect({it:numlist})}}select/order elements
    {p_end}
{synopt:{helpb symbolpalette##reverse:{ul:r}everse}}arrange palette in reverse order
    {p_end}
{synoptline}


{synoptset 20 tabbed}{...}
{marker gopts}{synopthdr:graph_options}
{synoptline}
{syntab:Main}
{synopt:{helpb symbolpalette##title:{ul:ti}tle({it:string})}}custom graph title
    {p_end}
{synopt:{helpb symbolpalette##gropts:{ul:gr}opts({it:options})}}options to be
    passed through to the graph command
    {p_end}

{syntab:Syntax 1 only}
{synopt:{helpb symbolpalette##rows:rows({it:#})}}minimum number of rows; default is 5
    {p_end}
{synopt:{helpb symbolpalette##nograph:{ul:nogr}aph}}do not generate a graph
    {p_end}

{syntab:Syntax 2 only}
{synopt:{helpb symbolpalette##horizontal:{ul:hor}izontal}}horizontal plot; the default
    {p_end}
{synopt:{helpb symbolpalette##vertical:{ul:vert}ical}}vertical plot
    {p_end}
{synopt:{helpb symbolpalette##labels:{ul:lab}els({it:strlist})}}custom palette labels
    {p_end}
{synopt:{helpb symbolpalette##msize:{ul:msiz}e({it:msizestyle})}}size of markers
    {p_end}
{synoptline}


{marker description}{...}
{title:Description}

{pstd}
    {cmd:symbolpalette} is a utility command to retrieve or display
    symbol palettes. Palette entries are returned in
    {helpb symbolpalette##returns:r()}.

{pstd}
    {cmd:symbolpalette} is used by {helpb grstyle set}.


{marker options}{...}
{title:Options}

{dlgtab:Palette options}

{marker n}{...}
{phang}
    {opt n(#)} specifies the size of the palette (the number
    of elements). Typically this just selects the first {it:#} elements from the
    palette and is thus equivalent to {cmd:select(1/}{it:#}{cmd:)}.

{marker select}{...}
{phang}
    {opth select(numlist)} selects and orders the elements retrieved from
    the palette.

{marker reverse}{...}
{phang}
    {opt reverse} returns the palette in reversed order.

{dlgtab:Graph options}

{marker title}{...}
{phang}
    {opt title(string)} specifies a custom title for the graph.

{marker gropts}{...}
{phang}
    {cmd:gropts(}{it:{help twoway_options}}{cmd:)} provides options to
    be passed through to the graph command.

{marker rows}{...}
{phang}
    {opt rows(#)} specifies the minimum number of rows in the graph (syntax 1
    only). The default is 5.

{marker nograph}{...}
{phang}
    {opt nograph} suppresses the graph (syntax 1 only).

{marker horizontal}{...}
{phang}
    {opt horizontal} displays the palettes horizontally (syntax 2 only). This
    is the default.

{marker vertical}{...}
{phang}
    {opt vertical} displays the palettes vertically (syntax 2 only).

{marker labels}{...}
{phang}
    {opt labels(strlist)} provides custom labels for the palettes (syntax 2
    only). Enclose labels with spaces in double quotes.

{marker msize}{...}
{phang}
    {opth msize(markersizestyle)} sets the size of the marker symbols (syntax 2
    only). Default is {cmd:msize(large)}.


{marker palettes}{...}
{title:Palettes}

{marker default}{...}
{dlgtab:default}

{pstd}
    Palette {cmd:default} ({stata symbolpalette default:{it:view}}) contains the symbols
    used for p1 to p15 in Stata's monochrome schemes. {cmd:default} is
    the default palette.

{marker lean}{...}
{dlgtab:lean}

{pstd}
    Palette {cmd:lean} ({stata symbolpalette lean:{it:view}}) contains the symbols
    used for p1 to p15 in schemes {cmd:lean1} and {cmd:lean2}
    by {browse "http://www.stata-journal.com/article.html?article=gr0002":Juul (2003)}.

{marker tufte}{...}
{dlgtab:tufte}

{pstd}
    Palette {cmd:tufte} ({stata symbolpalette tufte:{it:view}}) contains the symbols
    used for p1 to p15 in the {cmd:tufte} scheme
    by {browse "http://ideas.repec.org/c/boc/bocode/s457285.html":Atz (2011)}.

{marker pplain}{...}
{dlgtab:pplain}

{pstd}
    Palette {cmd:pplain} ({stata symbolpalette pplain:{it:view}}) contains the symbols
    used for p1 to p15 in the {cmd:plotplain} scheme
    by {browse "http://www.stata-journal.com/article.html?article=gr0070":Bischof (2017)}.

{marker pplain}{...}
{dlgtab:pplain}

{pstd}
    Palette {cmd:pplain} ({stata symbolpalette pplain:{it:view}}) contains the symbols
    used for p1 to p14 in the {cmd:plotplainblind} scheme
    by {browse "http://www.stata-journal.com/article.html?article=gr0070":Bischof (2017)}.

{marker symbollist}{...}
{dlgtab:symbollist}

{pstd}
    Instead of using a named palette you can provide a custom palette by
    specifying a list of {help symbolstyle:{it:symbolstyles}}. Example:

        . {stata symbolpalette X smplus s t}

{marker myname}{...}
{dlgtab:myname}

{pstd}
    A personal named palette can be provided in form of a program called {cmd:symbolpalette_}{it:myname}, where
    {it:myname} is the name of the palette. Palette {it:myname} will then be available to
    {cmd:symbolpalette} like any other palette. Your program should return the symbol definitions
    as a comma-separated list in local macro {cmd:P}. Example:

        {com}program symbolpalette_hollow
            c_local P Oh,Dh,Th,Sh,oh,dh,th,sh
        end{txt}

{pstd}
    After defining the program, you can, for example, type

        {com}. symbolpalette hollow{txt}

{pstd}
    to view the palette.


{marker examples}{...}
{title:Example}

        . {stata sysuse auto, clear}
        . {stata separate price, by(rep) shortlabel}
        . {stata symbolpalette tufte, n(5) nograph}
        . {stata scatter price? weight, ytitle(Price) msymbol(`r(p)')}


{marker returns}{...}
{title:Saved results}

{pstd}
    {cmd:symbolpalette} stores the following in {cmd:r()} (Syntax 1 only):

{synoptset 16 tabbed}{...}
{p2col 5 16 20 2: Scalars}{p_end}
{synopt:{cmd:r(n)}}number of returned palette entries{p_end}

{synoptset 16 tabbed}{...}
{p2col 5 16 20 2: Macros}{p_end}
{synopt:{cmd:r(ptype)}}{cmd:symbol}{p_end}
{synopt:{cmd:r(pname)}}name of palette{p_end}
{synopt:{cmd:r(pnote)}}additional information on palette (if provided){p_end}
{synopt:{cmd:r(p)}}space separated list of palette entries{p_end}
{synopt:{cmd:r(p#)}}#th palette entry{p_end}
{synopt:{cmd:r(p#info)}}info of #th palette entry (if provided){p_end}


{marker references}{...}
{title:References}

{phang}
    Atz, U. 2011. SCHEME TUFTE: Stata module to provide a Tufte-inspired
    graphics scheme. Available from
    {browse "http://ideas.repec.org/c/boc/bocode/s457285.html"}.
    {p_end}
{phang}
    Bischof, D. 2017. {browse "http://www.stata-journal.com/article.html?article=gr0070":New graphic schemes for Stata: plotplain and plottig}.
    The Stata Journal 17(3): 748–759.
    {p_end}
{phang}
    Juul, S. 2003. {browse "http://www.stata-journal.com/article.html?article=gr0002":Lean mainstream schemes for Stata 8 graphics}. The Stata
    Journal 3(3): 295-301.
    {p_end}


{marker author}{...}
{title:Author}

{pstd}
    Ben Jann, University of Bern, ben.jann@soz.unibe.ch

{pstd}
    Thanks for citing this software as

{pmore}
    Jann, B. (2018). {browse "https://www.stata-journal.com/article.html?article=gr0075":Color palettes for Stata graphics}. The Stata Journal
    18(4): 765-785.

{pstd}
    or

{pmore}
    Jann, B. (2017). palettes: Stata module providing color palettes, symbol
    palettes, and line pattern palettes. Available from
    {browse "http://ideas.repec.org/c/boc/bocode/s458444.html"}.


{marker alsosee}{...}
{title:Also see}

{psee}
    Online:  help for {helpb colorpalette}, {helpb colorpalette9}, {helpb linepalette}, {helpb grstyle set}, {helpb graph}, {help symbolstyle}

